Closes #198. Documentation-only, on top of #197 (merged), which is the substantive fix. This PR corrects docstrings that mislabeled the threaded allocation, and records the root-cause analysis + prototypes from investigating it.

What #198 turned out to be

1. The reported "~40 KB per completed integration" is a measurement artifact. The reproducer measures @allocated track!(rand(ComplexF32, n), …) with n = k·5000; the rand input buffer sits inside the @allocated block and is exactly n·8 B = 40 KB per 5000-sample code period, so it grows with completions. Hoisted out and measured from a typed call site, track! is flat 0 B across 1→100 completions, 1 and 11 sats, pre- and post-sync.

2. perf(bit-buffer): fix pre-sync per-code-block allocation in track! (re-target of #194 to master) #197 is the real fix. _buffer_find_bit's Core.Box leaked ~80 B/block (proportional to signal length — exactly the reported symptom). It reproduces on the single-threaded backend (160 B @ 2 blocks → 1600 B @ 20) at any runtime thread count, so the pre-sync guard added in perf(bit-buffer): fix pre-sync per-code-block allocation in track! (re-target of #194 to master) #197 catches it. With perf(bit-buffer): fix pre-sync per-code-block allocation in track! (re-target of #194 to master) #197 the single-threaded path is 0 B.

3. One genuine residual remains, on the threaded backend: ~64 B per completed code block per group, but only with >1 thread AND >1 satellite (so Polyester's @batch actually distributes work). track! launches one @batch per code block, so it scales with chunk length rather than per call — though it's bounded per call and dwarfed by the input buffer.

Root cause (now documented)

Polyester's @batch roots only bare Arrays and isbits values into its worker tasks for free (that's why a Vector{Float64} kernel is allocation-free). It pays a small per-launch allocation to root any non-isbits struct — and it's the struct-ness that costs, not the contents: capturing a plain struct whose only fields are Matrixes + isbits scalars measures the same ~64 B/launch, while capturing those same bare arrays measures 0 (verified).

The culprit is the GNSS signal: GPSL1CA is not isbits — it wraps a Matrix{Int16} code table and a (also non-isbits) SignalLUT. Each satellite's code-replica generation needs its signal, so every @batch launch touches that non-isbits object once. (The TrackedSat element is non-isbits for the same reason and is how the loop reaches the signal, so iterating Vector{TrackedSat} isn't free the way iterating Vector{Float64} is.)

Prototypes explored (not included — investigation only)

Two ways to reach 0 B were prototyped and measured:

Key findings:

• Bit-faithful in both cases (Δ = 0 vs the current per-sat path; the bare-array gen matched the real gen_code! exactly in 3/4 spot checks, off by 1 sample in the 4th due to fixed-point-DDA rounding).
• No speedups were found. The serial approach is slower; the bare-array approach is at best throughput-neutral. (Microbenchmarks are warm/min-time and exclude GC, so any long-run GC-pressure benefit from 0 B is unmeasured — and likely negligible next to the input buffer.)
• Hoisting the SignalLUT out of GPSL1CA does not help by itself (it's still a struct). Reaching 0 without a throughput hit needs a GNSSSignals-side bare-array gen_code! that threads the LUT's arrays + isbits fields to the SIMD resample kernel as separate arguments (never re-wrapped in a struct inside the loop — doing so hits a type-inference cliff and allocates far more). That's a cross-package API change for ~64 B/block, so it's left as a documented follow-up, not done here.

Changes in this PR

• src/track.jl, src/downconvert_and_correlate_cpu.jl: correct the docstrings that mislabeled the threaded residual as "~160 B per system per call" — it is per code block, only with >1 thread + >1 sat; document the non-isbits-signal root cause and the two 0-B routes (bare-array gen_code!, or the inferior serial pre-pass).
• test/track_in_place.jl: cross-reference track! post-sync per-integration allocation (~1.9 KB/completion/sat); original repro was measuring rand() — corrected #198 in the pre-sync allocation guard's rationale (it already pins allocation flat across completion counts).

The track! benchmark size is intentionally left at 2000 samples (no change).

🤖 Generated with Claude Code